Skip to content

Catalog: generic error details, contract check - #1224

Merged
neuromechanist merged 6 commits into
devfrom
fix/catalog-hygiene
Sep 3, 2026
Merged

neuromechanist merged 6 commits into
devfrom
fix/catalog-hygiene

Conversation

@neuromechanist

Copy link
Copy Markdown
Contributor

Summary

Two independently reviewed fixes to the public catalog routes in backend/src/routes/datasets/catalog.ts, each landed as its own commit.

The first fixes issue #1152: GET /datasets, GET /datasets/search, and GET /datasets/resolve/:id are anonymous endpoints that returned the raw Error#message as details on their failure paths, leaking table/column names and query shape to unauthenticated callers. The raw message is still logged server-side via console.error on every path, including a fallback catch that previously had no logging at all; the response now carries a generic, stable details string instead. The response shape and status codes are unchanged.

The second fixes issue #1207: nothing parsed a live catalog or detail response against the shared zod contract in shared/contract/dataset.ts, so a production regression in a derive path could ship data the contract calls invalid with no signal until a consumer's own parse threw. GET /datasets and GET /datasets/:id now safeParse their response against catalogItemSchema/datasetDetailSchema (via their envelope schemas) and log a bounded console.error naming the dataset id(s) and the first few zod issues on a mismatch. This is log-not-throw: a malformed response still reaches the caller unchanged, per ADR 0005. The check runs on every response in development/test; production samples at roughly 2%, applied uniformly to both routes, to keep the added cost negligible at catalog traffic volume.

Both fixes are scoped to backend/src/routes/datasets/catalog.ts per the issues; the audit of other route files with the same details:msg idiom is the issue's own stated follow-up, not in scope here.

Test plan

  • backend/test/catalog-anonymous-error-details.test.ts (new): drives GET /datasets, GET /datasets/search, and GET /datasets/resolve/:id through the real registered routes against a real bun:sqlite-backed D1, wrapped with a fault-injecting layer that throws a controlled, distinctive message from a specific query. Asserts the raw message never appears in the response body while still reaching console.error. Each of the four fixed call sites was verified to make its corresponding assertion fail when the fix was reverted one line at a time.
  • backend/test/catalog-contract-validation.test.ts (new): seeds a real D1 row with an out-of-enum zarr_verify_status (via the sweep_stamps JSON column, since the stored zarr_status column carries its own CHECK constraint and cannot hold an invalid value) through the real routes, and asserts the contract-violation log fires while the response still serves the invalid value unmodified. A positive-control test asserts a well-formed row produces no violation log. A statistical test bounds the production sampling rate between 1 and 200 violations over 1000 requests. Every assertion was verified to fail against a reverted or mutated version of the code it covers.
  • bun run lint -- clean.
  • bun x biome check backend/src backend/test shared -- 6 pre-existing errors and 1 warning in backend/src/services/zenodo.ts, backend/src/services/doi-orcid-discovery.ts, and backend/test/bucket-policy.test.ts, none touched by this PR (verified via git diff origin/dev showing zero diff on those files).
  • bun run typecheck -- clean.
  • bun test backend/test/catalog-anonymous-error-details.test.ts backend/test/catalog-contract-validation.test.ts backend/test/catalog-has-zarr.test.ts backend/test/dataset-detail-contract.test.ts backend/test/facet-filters-route.test.ts backend/test/facet-table-correspondence.unit.test.ts test/contract-live.test.ts test/contract-schemas.test.ts test/search-retrieval.test.ts test/search-min-score.unit.test.ts -- 315 pass, 6 skip, 0 fail.
  • bun test backend/test/ (full backend suite) -- 1645 pass, 0 fail.
  • Root bun test (full repo, includes test/api.test.ts, test/cli.test.ts, test/e2e-upload.test.ts): 52 pre-existing failures, all in the live-integration tier that requires a deployed backend plus TEST_ADMIN_API_KEY/TEST_USER_API_KEY, neither of which is available in this sandbox. None of the 52 failing tests are in catalog.ts, backend/test/, or shared/contract/; confirmed unrelated to this change.

Closes #1152
Closes #1207

GET /datasets, GET /datasets/search, and GET /datasets/resolve/:id
returned the raw Error#message as `details` to anonymous callers on
their failure paths, leaking table/column names and query shape.
The raw message is still logged server-side via console.error
(including a previously-unlogged fallback catch); the response now
carries a generic, stable details string instead.

Tested with backend/test/catalog-anonymous-error-details.test.ts,
which drives the real routes through a fault-injecting D1 wrapper
and asserts the raw message never appears in the response body
while still being logged. Each of the four fixed call sites was
verified to make its corresponding test fail when reverted.

Closes #1152
GET /datasets and GET /datasets/:id now safeParse their response
against the shared zod contract (catalogItemSchema/datasetDetailSchema
envelopes) and log a bounded console.error with the dataset id(s) and
first few issues on a mismatch. Log-not-throw: a malformed response
still reaches the caller unchanged.

Runs on every response in development/test; production samples at
~2% (uniform across both routes) to keep the added safeParse cost
negligible at catalog traffic volume.

Tested with backend/test/catalog-contract-validation.test.ts, which
seeds a real D1 row with an out-of-enum zarr_verify_status (via the
sweep_stamps JSON column, since the stored zarr_status column has its
own CHECK constraint) through the real routes and asserts the log
fires while the response still serves the invalid value unmodified.
A statistical test bounds the production sampling rate between 1 and
200 violations over 1000 requests. Each assertion was verified to
fail against a reverted/mutated version of the code it covers.

Closes #1207
@github-actions

github-actions Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

📦 Package Preview

Your package is ready to test!

bun install -g nemar-cli@PR1224

Version: 0.9.15-PR1224.754dca2
Commit: 754dca2


🤖 Updated on each push.

GET /datasets/:id served id as a raw D1 number (SELECT d.*) while
catalogItemSchema declares id: string, and file_size_formatted was
null for unmeasured file_size while datasetDetailSchema left it
non-nullable -- both meant the #1207 validation hook flagged every
well-formed detail response from day one.

Fixed at the source: id is stringified where the detail object is
built, and file_size_formatted is marked nullable on
datasetDetailSchema specifically, since the detail route's null vs
the list route's '' coalesce is a pre-existing, deliberate split
(the list route's file_size_formatted stays non-nullable, matching
its actual behavior).

Added the missing clean-pass positive control for GET /datasets/:id
(a well-formed row logs nothing) and removed the now-unnecessary
hand stringification workaround in catalog-has-zarr.test.ts.

Tested with backend/test/catalog-contract-validation.test.ts and
backend/test/catalog-has-zarr.test.ts (zero [contract] log lines).
Both fixes were verified independently: reverting either the id
stringification or the nullable schema change makes the new
positive-control test fail.
The safeParse/logContractViolation sequence ran synchronously before
return c.json(...), contradicting its own doc comment that it must
never observably add latency. deferContractCheck now schedules that
work on executionCtx.waitUntil, mirroring afterResponse() in
routes/auth-orcid.ts: the response returns first, the check runs
after, with the same try/catch fallback afterResponse uses (Hono's
Context#executionCtx throws when no ExecutionContext was provided,
so optional chaining alone is not enough) so a fire-and-forget
microtask still runs the check when there is none. Updated the doc
comment to describe what is actually guaranteed: latency isolation,
not zero cost -- the sampling rate is still what bounds production
CPU cost.

Test-side, added requestFlushed to catalog-contract-validation.test.ts,
mirroring zarr-data-cache.test.ts's requestWith: an explicit test
ExecutionContext whose waitUntil is collected and flushed via
Promise.allSettled before assertions run, replacing the implicit
(and now unverifiable-by-inspection) assumption that Hono's own
internal await chain would let the deferred microtask complete
before app.request() resolves.

Tested with backend/test/catalog-contract-validation.test.ts,
backend/test/catalog-has-zarr.test.ts, backend/test/facet-filters-route.test.ts,
backend/test/dataset-detail-contract.test.ts, and
backend/test/zarr-data-cache.test.ts.
The GET /datasets contract-violation log passed the whole page's
dataset_id array (up to 200) regardless of how many rows actually
failed. failedListRowIds derives the failing row ids from the zod
issue paths (datasets.<index>.<field>), dedups, and caps at 5, so
the log names only the rows that need attention.

Tested with backend/test/catalog-contract-validation.test.ts's new
mixed-page test (one well-formed row, one deliberately invalid),
which asserts the log names only the invalid row. Verified the test
fails when failedListRowIds is reverted to logging every row's id.
ANONYMOUS_ERROR_DETAILS gave no guidance. Appended retry/support
wording: "Please try again; if it persists, contact support."

Exported the constant and imported it in
catalog-anonymous-error-details.test.ts instead of hand-copying the
string, so the test can't silently drift from the real wording.

This branch was previously deployed

1 inactive deployment
npm — 754dca26 Deployed Sep 3, 2026 by neuromechanist via publish #2247
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant